Skip to content

Add v4 media endpoint with AI video descriptions#1197

Closed
evanc wants to merge 1 commit intofronzbot:devfrom
evanc:add-v4-media-ai-descriptions
Closed

Add v4 media endpoint with AI video descriptions#1197
evanc wants to merge 1 commit intofronzbot:devfrom
evanc:add-v4-media-ai-descriptions

Conversation

@evanc
Copy link
Copy Markdown

@evanc evanc commented Mar 1, 2026

Blink cameras have a new feature called Smart Video Descriptions (SVD) - the camera generates a short AI-written summary of each motion clip, like "A person is walking on the driveway" or "A delivery truck has arrived." These descriptions show up in the official Blink app, but blinkpy currently can't access them because they're only available through the newer v4 media endpoint.

This PR switches the media fetch from the legacy v1 endpoint to the v4 endpoint (POST /api/v4/accounts/{id}/media), which returns richer data including:

  • ai_vd — AI video descriptions with both a full and short summary
  • cv_detection — Computer vision labels (e.g., ["person"], ["vehicle"])
  • smart_video_descriptions — Account-level flag indicating SVD is enabled

The v4 endpoint is what the official Blink app already uses today; the v1 endpoint simply doesn't include these fields.

What changed

  • api.py — Added request_videos_v4() function for the v4 media POST endpoint
  • sync_module.pycheck_new_videos() now calls the v4 endpoint and extracts ai_vd and cv_detection from each media entry. Since v4 doesn't support the ?since= server-side filter that v1 had, client-side time filtering (which already existed via check_new_video_time()) handles this cleanly.
  • camera.py — Added ai_description, ai_description_short, and cv_detection attributes. Also fixed a URL-doubling bug: v4 returns absolute clip URLs (unlike v1's relative paths), so the code now checks before prepending base_url.
  • tests/test_ai_descriptions.py — 12 new tests covering the v4 API call, AI field extraction (present, absent, empty), camera attribute population, recent clips, and the absolute/relative URL handling.
  • tests/test_camera_functions.py — Updated recent_clips expected shape to include the new fields.

Backward compatibility

For accounts without SVD enabled, ai_vd comes back as None and the fields are simply omitted — no errors, no empty strings. The cv_detection and AI description attributes on the camera object default to None until populated, so existing integrations won't break.

Test plan

  • pytest — 230 tests pass (218 existing + 12 new)
  • ruff check — clean
  • black --check — clean
  • Tested locally against a live Blink account with SVD enabled

@evanc evanc force-pushed the add-v4-media-ai-descriptions branch from ab0e0b8 to 63958cf Compare March 1, 2026 02:46
Use the v4 media endpoint (POST /api/v4/accounts/{id}/media) in
check_new_videos() to fetch AI video descriptions (Smart Video
Descriptions) and top-level CV detection labels from Blink's API.

The v4 endpoint returns richer data than v1, including:
- ai_vd: AI-generated video descriptions (full and short)
- cv_detection: computer vision detection labels (e.g. person, vehicle)

New camera attributes: ai_description, ai_description_short, cv_detection.
Also fixes clip URL handling for absolute URLs returned by v4.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evanc evanc force-pushed the add-v4-media-ai-descriptions branch from 63958cf to 19009ab Compare March 1, 2026 02:49
@fronzbot
Copy link
Copy Markdown
Owner

fronzbot commented Mar 1, 2026

SVDs are only available to premium subscribers and this PR would break compatibility for those that don't subscribe. Source: https://support.blinkforhome.com/en_US/motion-detection/using-blink-video-descriptions

For that reason I'm going to have to deny the PR.

@fronzbot fronzbot closed this Mar 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants